Quartz 4

实战：使用 `.env` 文件管理环境变量的完整指南

8 min read

使用 .env 文件管理环境变量的完整指南

在现代前端开发中，环境变量的管理是一个非常重要的实践。无论是开发、测试，还是生产环境，我们常常需要根据不同的环境来调整配置，如 API 地址、调试模式、第三方服务密钥等。使用 .env 文件来管理这些环境变量是一个最佳实践，它可以使我们的配置更加集中、清晰，并且易于在不同的环境之间切换。

本文将详细介绍如何使用 .env 文件管理环境变量，并结合 Webpack 和 dotenv 库进行配置和使用。我们将涵盖以下内容：

  1. 什么是 .env 文件？
  2. 为什么要使用 .env 文件？
  3. 如何在项目中使用 dotenv 库来加载 .env 文件。
  4. 如何在 Webpack 中使用环境变量。
  5. 根据不同环境使用不同的 .env 文件。
  6. 使用 cross-env 实现跨平台环境变量设置。
  7. 使用 Webpack 的 EnvironmentPlugin。
  8. 使用环境变量的最佳实践。

1. 什么是 .env 文件？

.env 文件是一个纯文本文件，用于在项目中存储环境变量的键值对，每一行表示一个环境变量，格式为 KEY=VALUE。例如：

NODE_ENV=development
API_URL=https://api.dev.example.com
APP_SECRET_KEY=your-secret-key

注意：.env 文件通常放置在项目的根目录，并且应该被添加到 .gitignore 文件中，以避免在版本控制系统中暴露敏感信息。

2. 为什么使用 .env 文件？

使用 .env 文件的主要好处包括：

  • 集中管理配置：将所有环境变量集中在一个文件中，便于维护和管理。
  • 支持多环境配置：可以为不同环境（如开发、测试、生产）创建不同的 .env 文件，方便快速切换。
  • 增强安全性：将敏感信息存储在 .env 文件中，避免硬编码在源代码里，并可以通过 .gitignore 防止上传到版本控制系统。
  • 与其他工具兼容：.env 文件被许多工具和框架（如 Webpack、Node.js、React、Vue 等）支持，使其成为一种通用的配置管理方式。

3. 安装 dotenv 库

dotenv 是一个零依赖模块，用于将 .env 文件中的环境变量加载到 process.env 中。它非常适用于 Node.js 环境。

安装 dotenv：

npm install dotenv --save

4. 配置 Webpack 使用 .env 文件

为了在 Webpack 中使用 .env 文件，我们需要将 dotenv 库引入到 Webpack 配置中，并使用 DefinePlugin 插件将这些环境变量注入到应用程序中。

第一步：创建 .env 文件

在项目根目录下创建一个 .env 文件，并定义你的环境变量：

.env

NODE_ENV=development
API_URL=https://api.dev.example.com
APP_SECRET_KEY=your-secret-key

你还可以为生产环境创建一个单独的 .env.production 文件：

.env.production

NODE_ENV=production
API_URL=https://api.example.com
APP_SECRET_KEY=your-production-secret-key

第二步：在 Webpack 中加载 .env 文件

修改你的 Webpack 配置文件 webpack.config.js，引入 dotenv 并加载 .env 文件：

webpack.config.js

const path = require('path');
const webpack = require('webpack');
const dotenv = require('dotenv');
 
// 加载 .env 文件
const env = dotenv.config().parsed || {};
 
// 将环境变量转换为 Webpack DefinePlugin 所需的格式
const envKeys = Object.keys(env).reduce((prev, next) => {
  prev[`process.env.${next}`] = JSON.stringify(env[next]);
  return prev;
}, {});
 
module.exports = {
  mode: env.NODE_ENV || 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new webpack.DefinePlugin(envKeys), // 使用 DefinePlugin 注入环境变量
  ],
};

第三步：在代码中使用环境变量

现在你可以在 JavaScript 代码中通过 process.env 访问这些环境变量：

src/index.js

console.log('当前环境：', process.env.NODE_ENV);
console.log('API URL:', process.env.API_URL);
console.log('应用密钥：', process.env.APP_SECRET_KEY);

5. 根据环境加载不同的 .env 文件

为了在不同的环境中使用不同的 .env 文件，你可以根据 NODE_ENV 动态加载对应的 .env 文件。

修改 Webpack 配置

webpack.config.js

const path = require('path');
const webpack = require('webpack');
const dotenv = require('dotenv');
const fs = require('fs');
 
// 根据 NODE_ENV 加载不同的 .env 文件
const currentEnv = process.env.NODE_ENV || 'development';
const basePath = path.resolve(__dirname, `.env.${currentEnv}`);
const finalPath = fs.existsSync(basePath) ? basePath : path.resolve(__dirname, '.env');
 
const env = dotenv.config({ path: finalPath }).parsed || {};
 
const envKeys = Object.keys(env).reduce((prev, next) => {
  prev[`process.env.${next}`] = JSON.stringify(env[next]);
  return prev;
}, {});
 
module.exports = {
  mode: currentEnv,
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new webpack.DefinePlugin(envKeys),
  ],
};

6. 使用 cross-env 跨平台设置环境变量

在某些操作系统（如 Windows）中，直接使用 NODE_ENV=production 的方式设置环境变量可能不起作用。为了解决这个问题，可以使用 cross-env 库来实现跨平台的环境变量设置。

安装 cross-env

npm install cross-env --save-dev

在 package.json 中使用 cross-env

{
  "scripts": {
    "start": "cross-env NODE_ENV=development webpack serve --config webpack.config.js",
    "build": "cross-env NODE_ENV=production webpack --config webpack.config.js"
  }
}

7. 使用 Webpack 的 EnvironmentPlugin

除了 DefinePlugin 外，Webpack 还提供了 EnvironmentPlugin，它是 DefinePlugin 的一个快捷方式，用于从环境中传入变量。

使用 EnvironmentPlugin

修改 webpack.config.js：

const path = require('path');
const webpack = require('webpack');
 
module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new webpack.EnvironmentPlugin(['NODE_ENV', 'API_URL']) // 使用 EnvironmentPlugin
  ]
};

设置默认值

你还可以为 EnvironmentPlugin 提供默认值：

new webpack.EnvironmentPlugin({
  NODE_ENV: 'development',
  API_URL: 'https://api.dev.example.com'
})

8. 使用环境变量的最佳实践

  • 确保敏感信息安全：避免在前端代码中暴露敏感信息（如密钥和凭证），尽量将敏感信息处理放在后端。
  • 使用 .env 文件管理配置：将所有环境相关的配置放在 .env 文件中，便于集中管理。
  • 根据环境动态加载配置：根据当前环境动态加载不同的 .env 文件，确保配置的灵活性。
  • 使用 cross-env 实现跨平台兼容：在 npm 脚本中使用 cross-env 设置环境变量，以确保在不同操作系统上具有相同的行为。
  • 在 Webpack 中使用 DefinePlugin 或 EnvironmentPlugin：确保所有环境变量都在构建时注入到应用中，避免在运行时出现问题。

总结

通过使用 .env 文件管理环境变量，结合 Webpack 的 DefinePlugin 和 dotenv，你可以更加灵活和安全地管理前端项目的配置。根据环境加载不同的 .env 文件，确保你的应用在开发、测试和生产中的一致性和安全性。同时，使用 cross-env 确保在不同平台上的一致性设置。

这样你就可以轻松管理环境变量，使得你的应用程序更加灵活、可维护和安全。

Graph View